docs: refresh README, add docs index and link checker, fix stale paths#584
Conversation
- README: correct the verify:cheap chain, document verify:pr-local, and rewrite the CI paragraph to match the risk-scoped ci.yml jobs (changes/static-pr/pr-required aggregate, gated release-browser-matrix) - Add docs/README.md: categorized index of all docs distinguishing maintained docs from point-in-time records and archive - Rewrite docs/agents-guide.md as a non-duplicating pointer to AGENTS.md, codebase-index, and the new docs index - Add scripts/check-docs-links.mjs + `npm run docs:check-links` (advisory; not wired into verify chains) to catch dead repo-path references - Fix stale references it found: phantom favourites-home-page.tsx in the site-map generator (regenerated docs/site-map.md), ambiguous src/lib/supabase paths in codebase-index, archived phase-0 link in search-rag-master-context Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
This pull request has been ignored for the connected project Preview Branches by Supabase. |
📝 WalkthroughWalkthroughDocumentation navigation and verification guidance were expanded, a documentation link-checking command was added, onboarding references were updated, and stale module, archive, and site-map paths were synchronized. ChangesDocumentation maintenance
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 7❌ Failed checks (1 warning, 6 inconclusive)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
✨ Simplify code
Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0d8b6190c5
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
@codex resolve actionable Codex review findings for this pull request and current head using the repository instructions. This is the pull request's single automatic repair pass: do not perform a fresh review, create new standalone findings, or request another review. Work only the existing unresolved Codex threads on the current head. Always fix P0 and P1 findings. For P2 and lower findings, fix only clear, scoped, low-risk issues; otherwise disposition them with a concise reason. After fixing or dispositioning a thread, reply in that thread with as the first line, followed by a concise summary; that marker authorizes the workflow to close that exact thread. If human input or new authorization is required, do not use the marker and leave the thread open with the blocker. Finish only after every actionable thread is fixed or dispositioned and closed, or explicitly left open for a human decision. Do not update the branch from main, address unrelated reviews, broaden scope, or create more than one scoped fix commit. Do not use external APIs, paid services, credentials, dependency changes, or broad refactors unless explicitly authorized. Add targeted tests where behavior changes and run the narrowest relevant validation. |
|
To use Codex here, create a Codex account and connect to github. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@scripts/check-docs-links.mjs`:
- Around line 76-79: Update the Markdown link handling in the checker’s matchAll
loop to resolve relative targets against the scanned file’s directory, while
preserving root-relative handling. Normalize the resolved path and only validate
candidates whose canonical location remains under repoRoot, rejecting links that
escape the repository; ensure links in docs/README.md and docs/agents-guide.md
are included.
- Around line 54-61: Update the directory traversal around scanAll so maintained
nested documentation directories, including docs/redesign and docs/superpowers,
are scanned by default. Keep dated, audit, and archive directories excluded
unless scanAll is enabled, while preserving the existing Markdown target
collection behavior.
🪄 Autofix (Beta)
❌ Autofix failed (check again to retry)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: adca9ff8-987e-46a6-8d96-f6587e196e3e
📒 Files selected for processing (9)
README.mddocs/README.mddocs/agents-guide.mddocs/codebase-index.mddocs/search-rag-master-context.mddocs/site-map.mdpackage.jsonscripts/check-docs-links.mjsscripts/generate-site-map.ts
…stinstall - check-docs-links: markdown link targets now resolve relative to the containing file (and accept the repo-root-relative convention), are confined to the repository root, and docs/redesign + docs/superpowers are scanned by default while archive/audit/dated records stay behind --all (review findings from Codex and CodeRabbit) - Dockerfile + Dockerfile.worker: copy scripts/install-git-hooks.mjs into the npm ci stages — main's #583 added it as the npm postinstall hook, so every image build failed at npm ci with the module missing Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: fa75ccbf89
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
Note Autofix is a beta feature. Expect some limitations and changes as we gather feedback and continue to improve it. Autofix skipped. No unresolved CodeRabbit review comments with fix instructions found. |
1 participant
Summary
Documentation and doc-infrastructure refresh, plus a small image-build fix for a main-side regression this PR's CI surfaced.
verify:cheapchain description (it had drifted frompackage.json— the chain now includescheck:github-actions,brand:check,check:type-scale,check:icon-scale), documented the missingverify:pr-localgate (including the--dry-run --filesinspection form), and rewrote the CI paragraph to match the actual risk-scopedci.ymljobs (changes/static-pr/pr-requiredaggregate, path-scoped coverage/build/ui-critical/db-reset-verify, gatedrelease-browser-matrix).docs/README.md: categorized index of all ~85 docs, distinguishing maintained documents from point-in-time records and archive, marking generated files with their update commands. No docs were moved or deleted, so all inbound links keep resolving.docs/agents-guide.md: rewritten as a short non-duplicating pointer toAGENTS.md,docs/codebase-index.md, and the new index, so it can no longer drift from the authoritative agent rules.scripts/check-docs-links.mjs+npm run docs:check-links: verifies repo-path references in the maintained doc surface resolve. Markdown link targets are resolved relative to the containing file (repo-root-style targets also accepted) and confined to the repository root;docs/redesign/anddocs/superpowers/are scanned by default whilearchive/,audit/, and dated point-in-time records stay behind--all(per Codex + CodeRabbit review). Advisory tool only — deliberately not wired intoverify:cheapor CI.favourites-home-page.tsxin the site-map generator route-ownership table (real file isfavourites-command-library-page.tsx;docs/site-map.mdregenerated), ambiguoussupabase/client.tsx-style paths indocs/codebase-index.md(nowsrc/lib/supabase/), and an un-updated link to the archived phase-0 baseline indocs/search-rag-master-context.md.scripts/install-git-hooks.mjsinto thenpm cistages. feat(dx): Wave 1 session guards — retire repeated push-time traps #583 (merged to main after this branch was cut) added it as the npmpostinstallhook, so bothapp-imageandworker-imagebuilds failed atnpm ciwith the module missing. This branch mergedorigin/mainto pick up the script.Clinical governance preflight
N/A — documentation, an advisory doc-link script, and a Dockerfile dependency-stage COPY only. No ingestion, answer generation, search/ranking, source rendering, document access, privacy, production env, or clinical output changes.
Verification
npm run sitemap:update+npm run sitemap:check— green (regenerated map committed)npm run brand:check— greennode scripts/check-docs-links.mjs— 760 repo path references resolve on the default surface;--allfails only on historical/dated docs, as designednpx eslint scripts/check-docs-links.mjs scripts/generate-site-map.ts— cleannpx vitest run tests/site-map.test.ts— 5/5 passed (re-run after merging main)🤖 Generated with Claude Code